Specifying Page Ranges in the Job Collection(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Using Printing-Related Collection Objects

Specifying Page Ranges in the Job Collection
You can specify the page range and page range constraints in the page-range information job collection item. QuickDraw GX provides three kinds of representations for page ranges: simple numeric From and To values called the default page range, a single editable text field that specifies a replacement page range, and alphanumeric From and To values called a customized page range.
Listing 3-4 on page 3-29 shows how to set up a default page range for all pages to support the Print One Copy menu item of the File menu. The examples that follow show how to set up default, replacement, and customized page information for specific pages.
Listing 3-6 on page 3-33 shows how to set up the default page range for pages 1 through 4. The user may change these values to any within 1 and 9999.
Listing 3-6 Setting up a default page range
OSErr MyConfigurePageRange1(MyDocumentPtr myDocument)
{
   OSErr             err;
   gxPageRangeInfo   **pageRangeHdl;

   /*
      Create a handle to store the page range collection item in,
      and then retrieve the collection item.
   */
   pageRangeHdl
    = (gxPageRangeInfo **)NewHandleClear(sizeof(gxPageRangeInfo));
   nrequire_action(err, NewHandleClear_Failed, err = MemError(););

   err = GetCollectionItemHdl
                     (GXGetJobCollection(myDocument->documentJob),
                     gxPageRangeTag,
                     gxPrintingTagID,
                     (Handle) pageRangeHdl);
   nrequire(err, GetCollectionItemHdl_Failed);

   /*
      Use the standard "From-To" editable text field containing 
      default numeric values.
      Specify that the "all pages" radio button is not to be
      selected and that the "From" field contains 1 and the
      "To" field contains 4.
   */
   (*pageRangeHdl)->simpleRange.optionChosen = gxDefaultPageRange;
   (*pageRangeHdl)->simpleRange.printAll = false;

   (*pageRangeHdl)->simpleRange.fromPage = 1;
   (*pageRangeHdl)->simpleRange.toPage = 4;
   (*pageRangeHdl)->minFromPage = 1;
   (*pageRangeHdl)->maxToPage = 9999;

   /* Add (or replace) the collection item, and dispose of its
      handle. */
   err = AddCollectionItemHdl(
                     GXGetJobCollection(myDocument->documentJob),
                     gxPageRangeTag,
                     gxPrintingTagID,
                     (Handle) pageRangeHdl);

GetCollectionItemHdl_Failed:
   DisposHandle((Handle) pageRangeHdl);

NewHandleClear_Failed:
   return err;
}
Figure 3-9 shows the Print dialog box after executing the code to set the page range. QuickDraw GX obtains the page range to display from the collection item.
Figure 3-9 Print dialog box with default page range

Listing 3-7 shows how to set up a replacement page range, in which the From and To fields are replaced by a single editable text field. Note that the default editable text field is only one character, therefore, you almost always increase the size of the handle to accommodate the page range. The page range is a Pascal-style string.
Listing 3-7 Setting up a replacement page range
OSErr MyConfigurePageRange2(MyDocumentPtr myDocument)
{
   OSErr             err;
   gxPageRangeInfo   **pageRangeHdl;

   /*
      Create a handle to store the page range collection item in,
      and then retrieve the collection item.
   */
   pageRangeHdl
    = (gxPageRangeInfo **)NewHandleClear(sizeof(gxPageRangeInfo));
   nrequire_action(err, NewHandleClear_Failed, err = MemError(););

   err = GetCollectionItemHdl
                     (GXGetJobCollection(myDocument->documentJob),
                     gxPageRangeTag,
                     gxPrintingTagID,
                     (Handle) pageRangeHdl);
   nrequire(err, GetCollectionItemHdl_Failed);

   /*
      Replace the standard "From-To" editable text fields, with a
      single editable text field that contains "Chapter 5."
      Specify that the "all pages" radio button is not to be
      selected.
   */
   (*pageRangeHdl)->simpleRange.optionChosen = gxReplacePageRange;
   (*pageRangeHdl)->simpleRange.printAll = false;
   SetHandleSize((Handle) pageRangeHdl, 
                  sizeof(gxPageRangeInfo) +titleSize-1);
   nrequire_action(err, SetHandleSize_Failed, err = MemError(););
   BlockMove(FromToTitle, (*pageRangeHdl)->replaceString,
            titleSize);

   /* Add (or replace) the collection item, and dispose of its
      handle. */
   err = AddCollectionItemHdl(
                     GXGetJobCollection(myDocument->documentJob),
                     gxPageRangeTag,
                     gxPrintingTagID,
                     (Handle) pageRangeHdl);

SetHandleSize_Failed:
GetCollectionItemHdl_Failed:
   DisposHandle((Handle) pageRangeHdl);

NewHandleClear_Failed:
   return err;
}
Figure 3-10 shows the Print dialog box after executing the replacement page range code. The contents of the title, "Chapter 5," are displayed in a single editable text field. You must check for the validity of this field if the user changes it. For more information about parsing a page range to test its validity, see "Parsing Page Ranges" on page 3-73.
Figure 3-10 Print dialog box with replacement page range

Listing 3-8 shows how to set up a customized page range, in which the From and To fields allow editable text.
Listing 3-8 Setting up a customized page range
OSErr MyConfigurePageRange3(MyDocumentPtr myDocument)
{
   OSErr             err;
   gxPageRangeInfo   **pageRangeHdl;

   /*
      Create a handle to store the page range collection item in,
      and then retrieve the collection item.
   */
   pageRangeHdl
    = (gxPageRangeInfo **)NewHandleClear(sizeof(gxPageRangeInfo));
   nrequire_action(err, NewHandleClear_Failed, err = MemError(););

   err = GetCollectionItemHdl
                     (GXGetJobCollection(myDocument->documentJob),
                     gxPageRangeTag,
                     gxPrintingTagID,
                     (Handle) pageRangeHdl);
   nrequire(err, GetCollectionItemHdl_Failed);

   /*
      Use the standard "From-To" editable text fields, but they 
      now contain a custom format for the page range values.
      Specify that the "all pages" radio button is not to be
      selected and that the "From" field contains "iii" and the
      "To" field contains "VI".
   */
   (*pageRangeHdl)->simpleRange.optionChosen =
                                             gxCustomizePageRange;
   (*pageRangeHdl)->simpleRange.printAll = false;
   BlockMove("iii", &(*pageRangeHdl)->fromString[1], 3);
   (*pageRangeHdl)->fromString[0] = 3;
   BlockMove("VI", &(*pageRangeHdl)->toString[1], 2);
   (*pageRangeHdl)->toString[0] = 2;

   /* Add (or replace) the collection item, and dispose of its
      handle. */
   err = AddCollectionItemHdl(
                     GXGetJobCollection(myDocument->documentJob),
                     gxPageRangeTag,
                     gxPrintingTagID,
                     (Handle) pageRangeHdl);

GetCollectionItemHdl_Failed:
   DisposHandle((Handle) pageRangeHdl);

NewHandleClear_Failed:
   return err;
}
Figure 3-11 shows the Print dialog box after executing the customized page range code. The contents of the From and To fields are now editable text. You must check for the validity of these fields if the user changes them. For more information about parsing a page range to test its validity, see "Parsing Page Ranges" on page 3-73.
Figure 3-11 Print dialog box with customized page range